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ABOUT THIS CHAPTER 


This chapter describes the List Manager Package, which lets you create, display, 
and manipulate lists. 


You should already be familiar with: 


e 


e 


e 


e 


resources, as discussed in the Resource Manager chapter 

the basic concepts and structures behind QuickDraw, particularly 
points, rectangles, and grafPorts 

the Toolbox Event Manager and the Window Manager 

packages in general, as described in the Package Manager chapter 


Warning: Early versions of the system resource file may not contain 


the List Manager Package. 
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ABOUT THE LIST MANAGER PACKAGE 


The List Manager Package is a tool for storing and updating elements of data 
within a list and for displaying the list in a rectangle within a window. It 
handles all hit-testing, selection, and scrolling of list elements within that 
list. In its simplest form, the List Manager Package can be used to display a 
"text-only" list of names; with some additional effort, it can be used to 
display an array of images and text. 


A list element is simply a group of consecutive bytes of data, so it can be used 
to store anything—a name, the bits of an icon, or the resource ID of an icon. 
There's no specific restriction on the size of a list element, but the total 
size of a list cannot exceed 32K bytes. 


Appearance of Lists 


A list is drawn in a window. When you create a list, you need to supply a 
pointer to the window to be used; the grafPort of this window becomes the port 
in which drawing is done. 


You must also supply a rectangle in which to display the list. You specify 
whether the list should use scroll bars and a size box. If you request scroll 
bars, they're drawn outside the rectangle (but within the window). If you 
request a size box, the List Manager leaves room for one but does not draw it; 
to draw the size box, see the Window Manager procedure DrawGrowIcon. The 
rectangle can take up the entire area of the content region (except for the 
Space needed by scroll bars, if any), or it can occupy only a small portion of 
the content region. 


List elements are displayed in cells; an element can be seen as the contents of 
a cell. Cells provide the basic structure of a list, and may or may not contain 
list elements. While list elements (the actual data) may vary in length, the 
cells in which they're displayed must be the same size for any given list. You 
can specify the horizontal and vertical size of a cell when you create a list; 
if either dimension is unspecified, the List Manager calculates a default 
dimension. 


The dimensions of a list are always specified as a number of rows and columns of 
cells. When you create a list, you can specify the number of cells it is to 
contain initially; if you don't, it's created with no cells. To add cells to an 
empty list, you call routines that add entire rows or columns of cells at a 
time. For instance, to add a single column of 15 cells to an empty list, you 
would first call a routine to add one column, followed by a routine adding 15 
rows. 


All cells are initially empty. Once you've added the rows and columns of a list, 
you can set the values of the cells. At some later point, you can also add empty 
rows and columns to a list that already contains data. 
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Drawing Lists 


The List Manager provides a drawing mode that you can set either on or off. When 
the drawing mode is on, all routines that affect the contents of cells, the 
number of rows or columns, the size of the window, or which cells are visible 
within the rectangle will cause drawing to happen. 


In certain cases, such as the insertion or setting of many cells (typically when 
the list is created), drawing is either unsightly or slow. In these cases, 
you'll want to set the drawing mode to off; when the action is completed, you 
can set the drawing mode back to on. 


The appearance and behavior of a list is determined by a routine called its list 
definition procedure, which is stored as a resource in a resource file. The List 
Manager calls the definition procedure to perform any additional list 
initialization (such as the allocation of storage space for the application), to 
draw a cell, to invert the highlight state of a cell, and to dispose of any data 
it may have allocated. 


The system resource file includes a list definition procedure for a standard 
text-only list. If you'd like another type of list, you'll have to write a list 
definition procedure, as described later in the section "Defining Your Own 
Lists". 
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LIST RECORDS 


The List Manager maintains all the information it requires for its operations on 
a particular list in a list record. A list record includes: 


¢ A pointer to the grafPort used by the list; it's set to the port 
of the window specified when the list is created. 

e The rectangle, given in the window's local coordinates, in which 
the list is to be displayed. 

« A rectangle that specifies, by row and column, the dimensions of the list. 

e A rectangle that determines, by row and column, which cells are 
currently visible. 

¢ A handle to the list definition procedure, which actually performs 
the drawing of the cells. 

e The size of a cell. 

e A field containing flags that control the selection process. 


The list record also contains a handle to the cell data. The data is stored as a 
contiguous block of data in list order (cells 0..n of row 0, cells 0..n of row 
1, and so on). The cell data is locked down only while it's being searched. 


The last field of the list record is an array of integers containing the offset 
of each cell's data within the contiguous block of cell data. The high-order bit 
of an array element is set if the corresponding cell is selected; the remaining 
15 bits contain the offset. This provides the maximum total data size of 32K, 
and an overhead of one word per cell. 


Warning: Since a variety of routines are provided for accessing cell data, 
you should never need to directly access the array of offsets or 
the data itself. 


The List Record Data Structure 


The exact data structure of a list record is as follows: 


TYPE Cell = Point; 

DataArray = PACKED ARRAY [0..32000] OF CHAR; 

DataPtr = “DataArray; 

DataHandle = “DataPtr; 

ListRec = RECORD 
rView: Rect; {list's display rectangle} 
port: GrafPtr; {list's grafPort} 
indent: Point; {indent distance} 
cellSize: Point; {cell size} 
visible: Rect; {boundary of visible cells} 
vScroll: ControlHandle; {vertical scroll bar} 
hScrolt: ControlHandle; {horizontal scroll bar} 
selFlags: SignedByte; {selection flags} 
lActive: BOOLEAN; {TRUE if active} 
LReserved: SignedByte; {reserved} 
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listFlags: SignedByte; {automatic scrolling flags} 
clikTime: LONGINT; {time of last click} 
clikLoc: Point; {position of last click} 
mouseLoc: Point; {current mouse location} 
LClikLoop: Ptr; {routine for LClick} 
LastClick: Cell; {last cell clicked} 
refCon: LONGINT; {list's reference value} 
listDefProc: Handle; {list definition procedure} 
userHandle: Handle; {additional storage} 
dataBounds: Rect; {boundary of cells allocated} 
cells: DataHandle; {cell data} 
maxIndex: INTEGER; {used internally} 
cellArray: ARRAY [1..1] OF INTEGER {offsets to data} 
END; 
ListPtr = “ListRec; 
ListHandle = “ListPtr; 


RView is the rectangle, given in the local coordinates of the grafPort, in which 
the list is displayed. Room for scroll bars is not included in this rectangle. 
If the list has scroll bars and is to fill the entire window, rView should be 15 
points smaller in each dimension than the grafPort. 


Port is the grafPort used by the list; it's set to the port of the window 
specified when the list is created. Indent is the distance in pixels that the 
list definition procedure should indent from the topLeft of the cell when 
drawing the contents. The default value for indent is 0, but it can be set by 
the list definition procedure. 


CellSize is the size of a cell in pixels. If it's not specified when the list is 
created, a default cell size is set. CellSize.v is set to the ascent plus 
descent plus leading of the port's font, and cellSize.h is set to 


(rView. right — rView.left) DIV (dataBounds. right — dataBounds. left) 


A cell is a box in which a list element is displayed. Cells are identified by 
their column and row numbers. In Figure 1, for instance, the highlighted cell is 
in column 1, row 2. 


Cells are declared as points, using the Point data type simply as a way of 
specifying the column and row number of a cell. Similarly, visible and 
dataBounds use the Rect data type to specify a rectangular set of cells as two 
diagonally opposite cell coordinates (rather than two diagonally opposite points 
in the local coordinates of a grafPort). 


DataBounds is the boundary of the cells currently allocated, specified by row 
and column. The list in Figure 1 (assuming the entire list is visible) has 
seventeen rows and five columns of cells. DataBounds for this list can be 
represented, using the QuickDraw rectangle notation (left,top)(right,bottom), as 
(0,0)(5,17). Notice that the column and row specified for the bottom right of 
dataBounds are 1 greater in each dimension than the column and row number of the 
bottom right cell. Thus, you can test to see if a cell is a valid cell within 
the boundary of a list using the statement: 


IF PtInRect(c,myList**.dataBounds) THEN... 
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The visible rectangle reflects which cells are currently within the visible part 
of the list; it's calculated by the List Manager according to the values you 
specify for rView, dataBounds, and cellSize when you create the list. 
(Visible.topLeft is the row and column of the top left visible cell; 
visible.botRight is 1 greater in both dimensions than the row and column of the 
bottom right visible cell.) For example, if only four cells—row 2, column 0; row 
2, column 1; row 3, column 0; and row 3, column l—are visible, the visible 
rectangle is (0,2)(2,4). You can test to see if a cell is visible using the 
statement: 


IF PtInRect(c,myList**.visible) THEN... 
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Figure 1-—A Sample List 
Figure 1—A Sample List 


SelFlags contains selection flags for the List Manager. It's initialized to 0; 
with this setting, the List Manager selects cells according to the Macintosh 
User Interface Guidelines. The meaning of these flags is explained below in the 
section "Cell Selection Algorithm". The listFlags field contains automatic 
scrolling flags; the List Manager sets these flags automatically when you 
specify scroll bars. There are predefined constants that let you set or test the 
status of the corresponding bits: 


CONST tUDoVAutoScroll 
LDoHAutoScroll 


2; {set to allow automatic vertical scrolling} 
1; {set to allow automatic horizontal scrolling} 


ClikLoc is the position of the last mouse click in local coordinates; you can 
use it in the list definition procedure to get the position within the cell. 
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LClikLoop is a pointer to the routine to be called during the LClick function, 
as described later. LastClick contains the cell coordinates of the last cell 
clicked in. 


RefCon is the list's reference value field, which the application may store into 
and access for any purpose. In addition, the application may use the field 
userHandle to store a handle to an additional storage area. 


CellArray contains offsets to the cell data. For each list element, this 
includes the bit indicating whether the cell is selected or not. 


The LClikLoop Field 


The lClikLoop field of a list record lets you specify a routine that will be 
called repeatedly (by the LClick function, described below) as long as the mouse 
button is held down within the rView rectangle or its scroll bars. 


Note: The LClick function performs automatic scrolling if the mouse is 
dragged outside the visible rectangle, so there's no need to write 
a list click loop routine to do automatic scrolling. 


The list click loop routine has no parameters and returns a Boolean value. You 
could declare a list click loop routine named MyClikLoop like this: 


FUNCTION MyClikLoop : BOOLEAN; 


The function should return TRUE. You must put a pointer to your list click loop 
routine in the lClikLoop field of the list record so that the List Manager will 
call your routine. 


Warning: Returning FALSE from your list click loop routine tells the 
LClick function that the mouse button has been released, which 
aborts LClick. 


Assembly-language note: Your routine should set register DO to 1; returning 
0 in register DO aborts LClick. For your convenience, 
register D5 contains the current mouse Location. 
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CELL SELECTION ALGORITHM 


The default algorithm used by the List Manager for user selection of cells 
follows the techniques described in the Macintosh User Interface Guidelines, as 
summarized below. 


1. If neither the Shift nor the Command key is held down, a click causes 
all current selections to be deselected, and the cell receiving the 
click to be selected. While the mouse button is held down and the 
mouse moved around, only the cell under the cursor is selected. 


2. If the Shift key is held down, then as long as the mouse button is 
down, the List Manager expands and shrinks a selected rectangle that's 
defined by the mouse location and the "anchor". When the mouse is first 
pressed, the List Manager calculates the smallest rectangle that encloses 
all selected cells. If the click is above or to the left of this 
rectangle (or on the top left corner), the bottom right corner of the 
rectangle becomes the anchor; otherwise the top left corner becomes the 
anchor. (If no cells are selected, the clicked cell is used as the 
anchor. ) 


3. If the Command key is held down, then while the mouse button is down, 
all cells that the mouse passes over are either selected or deselected. 
Like the inversion of a bit in a bitmap, if the initial cell was off, 
cells are turned on; otherwise they're turned off. 


The selFlags byte, initialized to 0 by the List Manager, contains flags that let 
you change the way selections work. Each flag is specified by a bit, as 
illustrated in Figure 2. 


1 to not highlight empty cells 

1 for Shift to use sense of first cell 

1 to not grow selections 43 rectareles 
1 to notextend Shift selections 

1 to tum off multiple selections with click 

1 for dragging without Shift key 

1 if only one selection ata time 


* reserved for use by the List Manager 


Figure 2-Selection Flags 
Figure 2-Selection Flags 
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The List Manager provides a predefined constant for each flag, in which the bit 
corresponding to that flag is set. 


CONST lOnlyOne -—128; {set if only one selection at a time} 


lExtendDrag = 64; {set for dragging without Shift key} 

UNoDisjoint = 32; {set to turn off multiple selections with click} 
LNoExtend = 16; {set to not extend Shift selections} 

LNoRect = 8; {set to not expand selections as rectangles} 
LUseSense = 4; {set for Shift to use sense of first cell} 
UNoNilHilite = 2; {set to not highlight empty cells} 


Setting one or more of bits 5—7 modifies the selection algorithm in the 
following ways: 


¢ If you set the lOnlyOne bit, only one cell can be selected at a time. 

¢ If you set the lNoDisjoint bit, multiple cells can be selected, but 
everything is deselected when the mouse button is pressed (even if 
the Shift or Command keys are held down). 

« If you set the lExtendDrag bit, clicking and dragging selects all 
cells in its path. (It works best if you also set lNoDisjoint, lNoRect, 
LUseSense, and LNoExtend. ) 


Bits 2-4 affect Shift selection. If all three are set, Shift selection works 
exactly like Command selection. 


¢ If you set the LNoRect bit, Shift selections are not dragged out as 
rectangles, but instead select everything they pass over. They use the 
anchor point, but do not shrink selections when you back over them. 

¢ If you set the LNoExtend bit, the click is used as the anchor point for 
Shift selections, and current selections are ignored. 

e If you set the lUseSense bit, the cell that's clicked determines 
whether cells are turned off or on. 


Bit 1, the LNoNilHilite bit, determines whether or not empty cells can be 
selected. If you set this bit, cells not containing data cannot be selected 
(that is, the list definition procedure isn't called to highlight empty cells). 


Note: For the convenience of your application's user, remember to conform 
to the Macintosh User Interface Guidelines for selection. 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
THE LIST MANAGER PACKAGE e 10 of 27 


USING THE LIST MANAGER PACKAGE 


The List Manager Package is automatically read into memory from the system 
resource file when one of its routines is called; it occupies a total of about 
5K bytes. 


Before using the List Manager, you must initialize QuickDraw, the Font Manager, 
the Window Manager, the Menu Manager, and TextEdit, in that order. 


Before creating a list, you must create a window in which the drawing will take 
place. To create a new list, call the LNew function. When you're done using a 
list, you should dispose of its data with LDispose. Before you dispose of the 
list, make sure you dispose of any data that you may have stored in the 
userHandle or refCon fields of the list record. 


To change the size of a list's cells, call LCellSize. 


The procedure LDoDraw controls whether operations performed on cells by List 
Manager routines cause drawing on the screen. 


To add rows or columns to the list, call LAddRow and LAddColumn. To delete rows 
or columns, call LDelRow and LDelColumn. These routines do all necessary 
updating of the screen if you've set drawing on with LDoDraw. 


To assign a value to a cell, call the procedure LSetCell. To append data to a 
cell, you can call LAddToCell; to clear the contents of a cell, call LClrCell. 
To get a cell's data, call LGetCell. The new value of a cell is displayed if 
you've set drawing on. 


Warning: If you add or delete rows or columns, change the data in a cell, 
or call a routine that may move or purge memory, pointers (to a 
cell's data) obtained by earlier calls to the List Manager may 
no longer be valid. 


To select or deselect a cell, call LSetSelect. To determine whether or not a 
cell is selected, call LGetSelect. LGetSelect can also be used to find the next 
selected cell in the list. 


The Window Manager NewWindow or GetNewWindow call generates an update event for 
the entire window. Call LUpdate in response to the update event, and all visible 
cells in the update region will be drawn (or redrawn). When you change the value 
or selection of a cell from your program, it's redisplayed only if drawing is 
on. If drawing is off, you can call the procedure LDraw to display the contents 
of the cell. 


If a mouse-down event occurs within the list's window, call LClick. This routine 
tracks the mouse, selecting cells and scrolling the display as necessary. The 
result of LClick is a Boolean value that is TRUE if a double-click occurred. You 
can discover which cell received the double-click by calling LLastClick. 
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If an activate or deactivate event occurs for the window containing the list, 
you should call the procedure LActivate. This routine highlights the selected 
cells and scroll bars as necessary. 


If the window containing the list has a size box (and you want the list to grow 
along with the window), call the Window Manager routines GrowWindow and 
SizeWindow as usual, then call LSize with the new size of the list. The list is 
automatically expanded to fill the new area and the scroll bars are updated 
accordingly. The drawing mode does not affect the updating of scroll bars in 
LSize. 


You can find a cell with specified contents by calling LSearch. The default 
search routine is the International Utilities Package function IUMagIDString, 
but you can pass LSearch another search routine if you wish. Given a cell, you 
can call LNextCell to find the next cell in the list. 


You can find the local coordinates of a given cell by calling LRect. To scroll 
the list, call LScroll. You can call LAutoScroll to make sure that the first 
selected cell is visible. It automatically places the first selected cell in the 
top left corner of the visible rectangle. 


All the data in a list is stored as a single block. You can find the offset of a 
particular cell's data using LFind. 
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LIST MANAGER PACKAGE ROUTINES 


Assembly-language note: You can invoke each of the List Manager routines 
with a macro that has the same name as the routine 
preceded by an underscore. These macros expand to 
invoke to trap macro Pack 0. The package determines 
which routine to execute from a routine selector, an 
integer that's passed to it in a word on the stack. 
The routine selectors are as follows: 


lActivate . EQU 0 LAutoScroll .EQU 16 


lAddColumn .EQU 4 LCellSize . EQU 20 
LAddRow . EQU 8 LClick . EQU 24 
lAddToCell .EQU 12 Lclrceltl . EQU 28 
lDelColumn .EQU 32 LNew . EQU 68 
LDelRow . EQU 36 LNextCell . EQU 72 
lDispose .EQU 40 Rect .EQU 76 
LDoDraw . EQU 44 Scroll . EQU 80 
Draw . EQU 48 LSearch . EQU 84 
LFind . EQU 52 LSetCell . EQU 88 
LGetCell . EQU 56 LSetSelect . EQU 92 
lGetSelect .EQU 60 Size .EQU 96 
lLastClick .EQU 64 1Update .EQU 100 


Creating and Disposing of Lists 


FUNCTION LNew (rView,dataBounds: Rect; cSize: Point; 
theProc: INTEGER; theWindow: WindowPtr; 
drawIt,hasGrow, scrollHoriz,scrollVert: BOOLEAN) : ListHandle; 


Call LNew to create a new list. It returns a handle to the new list. The list's 
grafPort is set to theWindow's port. If drawIt is FALSE, the list is not 
displayed. 


RView specifies, in the local coordinates of theWindow, the rectangle in which 
the list will be displayed. (Remember that this doesn't include space for scroll 
bars. If the list, including scroll bars, is to fill the entire window, rView 
should be 15 points smaller in each dimension than theWindow's portRect. ) 


DataBounds is the rectangle for specifying the initial array dimensions of the 
list. For example to preallocate space for a list that's 5 cells across by 10 
cells down, you should set dataBounds to (0,0)(5,10). If you want to allocate 
the space for a one-column list, set dataBounds to (0,0)(1,0) and use LAddRow. 


CSize.h and cSize.v are the desired height and width of each cell in pixels; if 
they're not specified, a default cell size is calculated (as described above). 


TheProc is the resource ID of your list definition procedure; for a text-only 
list, pass 0 and the default list definition procedure (about 150 bytes in size) 
will be used. The list definition procedure is called to initialize itself after 
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all other list record fields have been initialized; thus, it can use any of the 
values in the list record (or set particular fields, such as the indent 
distance). 


If hasGrow is TRUE, the scroll bars are sized so that there's room for a size 
box in the standard position. It's up to the program to display the size box 
(using the Window Manager procedure DrawGrowIcon). If scrollHoriz is TRUE, a 
horizontal scroll bar is placed immediately below rView and all horizontal 
scrolling functions are implemented. If scrollVert is TRUE, a vertical scroll 
bar is placed immediately to the right of rView and all vertical scrolling 
functions are implemented. 


The visible rectangle is set to contain as many cells of cSize (or the default) 
as will fit into rView. If the cells do not fit exactly into rView, the visible 
rectangle is rounded up to the nearest cell. Scrolling will always allow all 
cells to be fully displayed. The selection flags are set to 0, and the active 
flag is set to TRUE. 


Note: Scrolling looks best if rView is a multiple of cSize.v in height. 
PROCEDURE LDispose (lHandle: ListHandle) ; 

Call LDispose when you are through using a list. It issues a close call to the 
list definition procedure, and calls the Memory Manager procedure DisposHandle 
for the data handle, the Control Manager procedure DisposeControl for both 
scroll bars (if they're there), and DisposHandle for the list record. 


Note: Calling LDispose is much faster than deleting one row at a time. 


Adding and Deleting Rows and Columns 
FUNCTION LAddColumn (count,colNum: INTEGER; LHandle: ListHandle) : INTEGER; 


LAddColumn inserts into the given list the number of columns specified by the 
count parameter, starting at the column specified by colNum. Column numbers that 
are greater than or equal to colNum are increased by count. If colNum is not 
within dataBounds, new last columns are added. The number of the first added 
column is returned and dataBounds.right is increased by count. All cells added 
are empty. If there are no cells (because dataBounds.top = dataBounds.bottom), 
no cells are added, but dataBounds is still extended. If drawing is on and the 
added columns (which are empty) are visible, the list and its scroll bars are 
updated. 


FUNCTION LAddRow (count, rowNum: INTEGER; LHandle: ListHandle) : INTEGER; 


LAddRow inserts the number of rows specified by the count parameter, starting at 
the row specified by rowNum. Row numbers that are greater than or equal to 
rowNum are increased by count. If rowNum is not within dataBounds, new last rows 
are added. The number of the first added row is returned, and dataBounds.bottom 
is increased by count. All cells added are empty. If there are no cells 

(because dataBounds. left = dataBounds.right), no cells are added, but dataBounds 
is still extended. If drawing is on and the added rows (which are empty) are 
visible, the List and its scroll bars are updated. 


PROCEDURE LDelColumn (count,colNum: INTEGER; lHandle: ListHandle); 
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LDelColumn deletes the number of columns specified by the count parameter, 
starting with the column specified by colNum. Column numbers that are greater 
than colNum are decreased by count. If colNum is not within dataBounds, nothing 
is done. DataBounds.right is decreased by count. If drawing is on and the 
deleted columns were visible, the list and its scroll bars are updated. 


If count is 0, or 
colNum = dataBounds.left AND count > = dataBounds.right — dataBounds. left 


all the data in the list is quickly deleted, dataBounds.right is set to 
dataBounds.left, and the number of rows is left unchanged. 


PROCEDURE LDelRow (count, rowNum: INTEGER; lHandle: ListHandle) ; 
LDelRow deletes the number of rows specified by the count parameter, starting 
with the row specified by rowNum. Row numbers that are greater than rowNum are 
decreased by count. If rowNum is not within dataBounds, nothing is done. 
DataBounds.bottom is decreased by count. If drawing is on and the deleted rows 
were visible, the list and its scroll bars are updated. 
If count is 0, or 

rowNum = dataBounds.top AND count > = dataBounds.bottom — dataBounds.top 


all the data in the list is quickly deleted, dataBounds.bottom is set to 
dataBounds.top, and the number of columns is left unchanged. 


Operations on Cells 


PROCEDURE LAddToCell (dataPtr: Ptr; dataLen: INTEGER; theCell: Cell; 
lHandle: ListHandle); 


LAddToCell appends the data pointed to by dataPtr and of length dataLen to the 
cell specified by theCell in lHandle. If drawing is off, you must turn drawing 
on and call LDraw (or LUpdate) to display the cell's new value. 


PROCEDURE LCIrCell (theCell: Cell; lHandle: ListHandle); 


LClrCell clears the contents of the specified cell (by setting the length to 0). 
If theCell is not a valid cell, nothing is done. If drawing is off, you must 
turn drawing on and call LDraw to display the cell's new value (or simply call 
the Window Manager procedure InvalRect). 


PROCEDURE LGetCell (dataPtr: Ptr; VAR dataLen: INTEGER; theCell: Cell; 
lHandle: ListHandle); 


Given a cell in theCell, LGetCell copies the cell's data to the location 
specified by dataPtr; dataLen is the maximum number of bytes allowed. If the 
data is longer than dataLen, only dataLen bytes are copied into the location 
specified by dataPtr. If the data is shorter than dataLen, dataLen is set to the 
true length of the cell's data. 
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PROCEDURE LSetCell (dataPtr: Ptr; dataLen: INTEGER; theCell: Cell; 
lHandle: ListHandle); 


LSetCell places the data pointed to by dataPtr and of length dataLen into the 
specified cell. It replaces any data that was already in the cell. If dataLen is 
0, this is equivalent to LClrCell. If theCell is not a valid cell, nothing is 
done. If drawing is off, you must turn drawing on and call LDraw (or LUpdate) to 
display the cell's new value. 


PROCEDURE LCellSize (cSize: Point; LHandle: ListHandle); 


LCellSize sets the cellSize field in the list record to cSize and updates the 
visible rectangle to contain cells of this size. This command should be used 
only before any cells have been drawn. 


FUNCTION LGetSelect (next: BOOLEAN; VAR theCell: Cell; 
lHandle: ListHandle) : BOOLEAN; 


If next is FALSE, LGetSelect returns TRUE if the specified cell is selected, or 
FALSE if not. If next is TRUE, LGetSelect returns in c the cell coordinates of 
the next selected cell in the row that is greater than or equal to theCell. If 
there are no more cells in the row, it returns in theCell the cell coordinates 
of the next selected cell in the next row. If there are no more rows, FALSE is 
returned. 


PROCEDURE LSetSelect (setIt: BOOLEAN; theCell: Cell; lHandle: ListHandle); 
If setIt is TRUE, LSetSelect selects the cell and redraws if it is visible and 


was previously unselected. If setIt is FALSE, it deselects the cell and redraws 
if necessary. 


Mouse Location 


FUNCTION LClick (pt: Point; modifiers: INTEGER; 
lHandle: ListHandle) : BOOLEAN; 


Call LClick when there is a mouse-down event in the destination rectangle or its 
scroll bars. Pt is the mouse location in local coordinates. Modifiers is the 
modifiers word from the event record. LHandle is the list to be tracked. The 
result is TRUE if a double-click occurred (and the two clicks took place within 
the same cell). 


LClick keeps control until the mouse is released; each time through its inner 
loop, it calls the routine whose pointer is in the lClikLoop field of the list 
record. 


If the mouse is in the visible rectangle, cells are selected according to the 
state of the modifiers and the selection flags. If the mouse was in the cells 
but is dragged outside the list's rectangle, the list is auto-scrolled. If the 
mouse was in a control, the control's definition procedure is called to track 
the mouse. To discover which cell was clicked in, use the LLastClick function. 


FUNCTION LLastClick (lHandle: ListHandle) : Cell; 
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LLastClick returns the cell coordinates of the last cell clicked in. If no cell 
has been clicked in since LNew, the value returned (for both integers) is 
negative. 


Note: The value returned by this call is not the last cell double-clicked 
in, or the last cell selected, but merely the last cell clicked in. 


Accessing Cells 


PROCEDURE LFind (VAR offset,len: INTEGER; theCell: Cell; 
lHandle: ListHandle); 


Given a cell in theCell, LFind returns the offset and the length in bytes of the 
cell's data. If an invalid cell is specified, offset and len are set to -1. A 
Similar procedure, LGetCell, is more convenient to use from Pascal. 


FUNCTION LNextCell (hNext,vNext: BOOLEAN; VAR theCell: Cell; 
lHandle: ListHandle) : BOOLEAN; 


Given a cell in theCell, LNextCell returns in theCell the next cell in the list. 
If both hNext and vNext are TRUE, theCell is first advanced to the next cell in 
the row. If there are no more cells in the row, theCell is set to the first cell 
in the next row. If there are no more rows, FALSE is returned. If only hNext is 
TRUE, theCell is advanced within the current row. If only vNext is TRUE, theCell 
is advanced within the current column. FALSE is returned if there are no 
remaining cells in the row or column. 


PROCEDURE LRect (VAR cellRect: Rect; theCell: Cell; lHandle: ListHandle); 


LRect returns in cellRect the local (QuickDraw) coordinates of the cell 
specified by theCell. If an invalid cell is specified, (0,0)(0,0) is returned in 
cellRect. 


FUNCTION LSearch (dataPtr: Ptr; dataLen: INTEGER; searchProc: Ptr; 
VAR theCell: Cell; lHandle: ListHandle) : BOOLEAN; 


LSearch searches for the first cell greater than or equal to theCell that 
contains the specified data. If a cell containing matching data is found, the 
function result TRUE is returned, and the cell coordinates are returned in 
theCell. If searchProc is NIL, the International Utilities Package function 
IUMagIDString is called to compare the specified data with the contents of each 
cell. If searchProc is not NIL, the routine pointed to by searchProc is called. 


Note: Your searchProc should have the same parameters as the 
IUMagIDString function. 


PROCEDURE LSize (lListWidth,listHeight: INTEGER; lHandle: ListHandle); 


You'll usually call LSize immediately after the Window Manager procedure 
SizeWindow. It causes the bottom right of the list to be adjusted so that the 
list is the width and height indicated by listWidth and listHeight. The contents 
of the list and the scroll bars are adjusted and redrawn as necessary. The 
values of listWidth and listHeight do not include the scroll bars; for a list 
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that entirely fills the window, listWidth and listHeight should be 15 fewer 
pixels than the portRect if both scroll bars are present. 


List Display 
PROCEDURE LDraw (theCell: Cell; lHandle: ListHandle); 


Call LDraw after updating a cell's data or selection status. (You can achieve 
the same result by invalidating the cell's rectangle and calling LUpdate in 
response to the update event.) The List Manager makes its grafPort the current 
port, sets the clipping region to the cell's rectangle, and calls the list 
definition procedure to draw the cell. It restores the clipping region and port 
before exiting. 


PROCEDURE LDoDraw (drawIt: BOOLEAN; lHandle: ListHandle); 


LDoDraw sets the List Manager's drawing mode to the state specified by drawIt. 
If drawIt is TRUE, changes made by most List Manager calls will cause some sort 
of drawing to take place. If drawIt is FALSE, all cell drawing is disabled. 
(Two exceptions: The scroll bars are still updated after LSize, and the scroll 
arrows are still highlighted if the user clicks them. ) 


The recommended use of LDoDraw is to disable drawing while you're building a 
list (that is, adding rows or columns, setting or changing cell values, or 
setting default selections). Once you've finished building the list, you should 
then re-enable drawing. In general, drawing should be on while you're in your 
event loop and dispatching events to the List Manager. 


PROCEDURE LScroll (dCols,dRows: INTEGER; LHandle: ListHandle); 


LScroll scrolls the given list by the number of columns and rows specified in 
dCols and dRows, either positively (down and to the right) or negatively (up and 
to the left). Scrolling is pinned to the list's dataBounds. If drawing is on, 
LScroll does all necessary updating of the screen. 


PROCEDURE LAutoScroll (lHandle: ListHandle); 


For the given list, LAutoScroll scrolls the list until the first selected cell 
is visible. It automatically places the first selected cell in the top left 
corner of the visible rectangle. 


PROCEDURE LUpdate (theRgn: RgnHandle; lHandle: ListHandle) ; 


LUpdate should be called in response to an update event. TheRgn should be set to 
the visRgn of the list's port (for more details, see the BeginUpdate procedure 
in the Window Manager chapter). It redraws any visible cells in lHandle that 
intersect theRgn. It also redraws the controls, if necessary. 


PROCEDURE LActivate (act: BOOLEAN; lHandle: ListHandle); 
Call LActivate to activate or deactivate the list specified by lHandle (in 


response to an activate event in the window containing the list). The act 
parameter should be set to TRUE to activate the list, or FALSE to deactivate the 
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list. LActivate highlights or unhighlights the selections, and shows or hides 
the scroll bars (but not the size box, if any). 
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DEFINING YOUR OWN LISTS 


The List Manager calls a list definition procedure to perform any additional 
list initialization (such as the allocation of storage space for the 
application), to draw a cell, to invert the highlight state of a cell, and to 
dispose of any data it may have allocated. The system resource file includes a 
default list definition procedure for a standard text-only list; you may, 
however, wish to define your own type of List with special features. 


To define your own type of list, you write a list definition procedure and store 
it in a resource file as a resource of type 'LDEF'. The standard list definition 
procedure has a resource ID of 0; your definition procedure should have a 
different ID. 


When you create a list, you provide the resource ID of the list definition 
procedure to be used. The List Manager calls the Resource Manager to access the 
list definition procedure with the given resource ID. The Resource Manager reads 
the list definition procedure into memory and returns a handle to it. The List 
Manager then stores this handle in the listDefProc field of the list record. 


The List Definition Procedure 


The list definition procedure is usually written in assembly language, but may 
be written in Pascal. 


Assembly-language note: The procedure's entry point must be at the beginning. 


You may choose any name you wish for your list definition procedure. Here's how 
you would declare one named MyList: 


PROCEDURE MyList (lMessage: INTEGER; lSelect: BOOLEAN; lRect: Rect; 
Cell: Cell; Wata0ffset,lDataLen: INTEGER; 
lHandle: ListHandle); 


The lMessage parameter identifies the operation to be performed. It has one of 
the following values: 


CONST ULInitMsg = 0; {do any additional list initialization} 
lUDrawMsg = 1; {draw the cell } 
lHiliteMsg = 2; {invert cell's highlight state} 
lCloseMsg = 3; {take any additional disposal action} 


LSelect is used for both the drawing and highlighting operations; it's TRUE if 
the cell should be selected. 


LRect indicates the rectangle in which a cell should be drawn. LDataOffset is 
the offset into the cell data of the cell to be drawn or highlighted; ltDataLen 
is the length in bytes of that cell's data. LHandle is the handle to the list 
record. 
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The routines that perform these operations are described below. 


Note: "Routine" here doesn't necessarily mean a procedure or function. 
While it's a good idea to set these up as subfunctions within the 
list definition procedure, you're not required to do so. 


The Initialize Routine 


The list definition procedure is called by the LNew function with an initMsg 
message after all list initialization has been completed. Since all default 
settings have been stored in the list record, this routine is a good place to 
change any of these settings. This routine can also be used to allocate any 
private storage needed by the list definition procedure. 


The Draw Routine 


The list definition procedure receives a lDrawMsg message when a cell needs to 
be drawn. The lSelect parameter is TRUE if the given cell should be selected. 


LRect is the rectangle in which the cell should be drawn. The draw routine sets 
the clipping region of the list's window to this rectangle. 


LDataOffset is the offset into the cell data of the cell to be drawn; lDataLen 
is the length of that cell's data in bytes. 


The Highlight Routine 


The definition procedure receives a LHiliteMsg message when a cell's data is 
visible and its highlight state needs to be inverted (from selected to 
deselected or vice versa). This routine is provided for the extra speed usually 
gained by using an invert operation instead of a combination of the draw and 
highlight operations. 


The parameters for this routine are identical to those for the lDrawMsg routine. 
If you want (for instance, if highlighting is more complicated than mere 
inversion), you can simply call your lDrawMsg routine when you get a lLHiliteMsg 
message. 


The Close Routine 


The definition procedure receives a lCloseMsg message in response to a LDispose 
call. If any private storage was allocated by the definition procedure, this 
routine should dispose of it. 
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SUMMARY OF THE LIST MANAGER PACKAGE 


Constants 

CONST 
{ Masks for automatic scrolli 
LDoVAutoscroll = 2 {s 
UDoHAutoscroll =1 


{ Masks for selection flags } 


LOnlyOne = —-128; {set 
LExtendDrag = 64; {set 
LUNoDisjoint = 32; {set 
LNoExtend = 16; {set 
LNoRect = 8; {set 
lUseSense = 4; {set 
LNoNilHilite = 2" {set 


{ Messages to list definition 


{set 


ng } 


et 


procedure } 


to allow automatic vertical scrolling} 
to allow automatic horizontal scrolling} 


if only one selection at a time} 

for dragging without Shift key} 

to turn off multiple selections with click} 
to not extend Shift selections} 

to not grow selections as rectangles} 

for Shift to use sense of first cell} 

to not highlight empty cells} 


LInitMsg = 0; {initialize list, set defaults, allocate space} 

lDrawMsg = 1; {draw the indicated cell data} 

LHiliteMsg = 2; {invert (select/deselect) the state of a cell} 

lCloseMsg = 3; {dispose of list and any associated data} 

Data Types 
TYPE 

Cell = Point; 

DataArray = PACKED ARRAY [0..32000] OF CHAR; 

DataPtr = “DataArray; 

DataHandle = “DataPtr; 

ListRec = RECORD 
rView: Rect; {list's display rectangle} 
port: GrafPtr; {list's grafPort} 
indent: Point; {indent distance} 
cellSize: Point; {cell size} 
visible: Rect; {boundary of visible cells} 
vScroll: ControlHandle; {vertical scroll bar} 
hScrolt: ControlHandle; {horizontal scroll bar} 
selFlags: SignedByte; {selection flags} 
lActive: BOOLEAN; {TRUE if active} 
LReserved: SignedByte; {reserved} 
listFlags: SignedByte; {automatic scrolling flags} 
clikTime: LONGINT; {time of last click} 
clikLoc: Point; {position of last click} 
mouseLoc: Point; {current mouse Location} 
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LClikLoop: Ptr; {routine for LClick} 
LastClick: Cell; {last cell clicked} 
refCon: LONGINT; {list's reference value} 
listDefProc: Handle; {list definition procedure} 
userHandle: Handle; {additional storage} 
dataBounds: Rect; {boundary of cells allocated} 
cells: DataHandle; {cell data} 
maxIndex: INTEGER; {used internally} 
cellArray: ARRAY [1..1] OF INTEGER {offsets to data} 
END; 
ListPtr = “ListRec; 
ListHandle = “ListPtr; 
Routines 
Creating and Disposing of Lists 
FUNCTION LNew (rView,dataBounds: Rect; cSize: Point; 
theProc: INTEGER; theWindow: WindowPtr; 
drawIt, hasGrow,scrollHoriz,scrollVert: BOOLEAN) 
ListHandle; 
PROCEDURE LDispose (lHandle: ListHandle) ; 
Adding and Deleting Rows and Columns 
FUNCTION LAddColumn (count,colNum: INTEGER; lHandle: ListHandle) INTEGER; 
FUNCTION LAddRow (count, rowNum: INTEGER; lHandle: ListHandle) INTEGER; 
PROCEDURE LDelColumn (count,colNum: INTEGER; lHandle: ListHandle); 
PROCEDURE LDelRow (count, rowNum: INTEGER; lHandle: ListHandle); 
Operations on Cells 
PROCEDURE LAddToCell (dataPtr: Ptr; dataLen: INTEGER; theCell: Cell; 
lHandle: ListHandle); 
PROCEDURE LClUrCell (theCell: Cell; lHandle: ListHandle); 
PROCEDURE LGetCell (dataPtr: Ptr; VAR dataLen: INTEGER; theCell: Cell; 
lHandle: ListHandle); 
PROCEDURE LSetCell (dataPtr: Ptr; dataLen: INTEGER; theCell: Cell; 
lHandle: ListHandle); 
PROCEDURE LCellSize (cSize: Point; LHandle: ListHandle ); 
FUNCTION LGetSelect (next: BOOLEAN; VAR theCell: Cell; 
lHandle: ListHandle) BOOLEAN; 
PROCEDURE LSetSelect (setIt: BOOLEAN; theCell: Cell; lHandle: ListHandle); 
Mouse Location 
FUNCTION LClick (pt: Point; modifiers: INTEGER; 
lHandle: ListHandle) BOOLEAN; 
FUNCTION LLastClick (lHandle: ListHandle) Cell; 
Accessing Cells 
PROCEDURE LFind (VAR offset,len: INTEGER; theCell: Cell; 
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lHandle: ListHandle); 
FUNCTION LNextCell (hNext,vNext: BOOLEAN; VAR theCell: Cell; 
lHandle: ListHandle) : BOOLEAN 
PROCEDURE LRect (VAR cellRect: Rect; theCell: Cell; lHandle: ListHandle); 
FUNCTION LSearch (dataPtr: Ptr; dataLen: INTEGER; searchProc: Ptr; 
VAR theCell: Cell; lHandle: ListHandle) : BOOLEAN; 
PROCEDURE LSize (listWidth, ListHeight: INTEGER; lHandle: ListHandle); 
List Display 
PROCEDURE LDraw (theCell: Cell; lHandle: ListHandle); 
PROCEDURE LDoDraw (drawIt: BOOLEAN; LHandle: ListHandle); 
PROCEDURE LScroll (dCols,dRows: INTEGER; lLHandle: ListHandle); 
PROCEDURE LAutoScroll (lHandle: ListHandle); 
( 
( 


PROCEDURE LUpdate theRgn: RgnHandle; lHandle: ListHandle) ; 
PROCEDURE LActivate act: BOOLEAN; lHandle: ListHandle) ; 


List Definition Procedure 


PROCEDURE MyListDef (lMessage: INTEGER; lSelect: BOOLEAN; lRect: Rect; 
Cell: Cell; Wata0ffset,lDataLen: INTEGER; 
lHandle: ListHandle); 


Assembly-Language Information 
Constants 
; Automatic scrolling flags 


UoVAutoscroll .EQU 1 ;set to allow automatic vertical scrolling 
UDoHAutoscroll .EQU 0 ;set to allow automatic horizontal scrolling 


; Selection flags 


LOnlyOne .EQU 7 ;set if only one selection at a time 
LExtendDrag . EQU 6 ;set for dragging without Shift key 

LUNoDisjoint .EQU 5 ;set to turn off multiple selections with click 
LNoExtend .EQU 4 ;set to not extend Shift selections 

LNoRect .EQU 3 ;set to not grow selections as rectangles 
lUseSense . EQU 2 ;set for Shift to use sense of first cell 
LNoNilHilite . EQU 1 ;set to not highlight empty cells 


; Messages to list definition procedure 


LInitMsg . EQU 0 ;initialize list, set defaults, allocate space 
UrawMsg . EQU 1 ;draw the indicated cell data 

LHiliteMsg . EQU 2 ;invert (select/deselect) the state of a cell 
LCloseMsg .EQU 3 ;dispose of list and any associated data 


; Routine selectors 
; (Note: You can invoke each of the List Manager routines with a macro 
; that has the same name as the routine preceded by an underscore. ) 
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lActivate . EQU 0 


LAddColumn . EQU 4 

LAddRow . EQU 8 

LAddToCell . EQU 12 
LAutoScroll . EQU 16 
lCellSize . EQU 20 
LClick . EQU 24 
Lclrcell . EQU 28 
LDelColumn . EQU 32 
LDelRow . EQU 36 
lDispose .EQU 40 
LDoDraw . EQU 44 
Draw . EQU 48 
LFind . EQU 52 
lGetCell .EQU 56 
LGetSelect . EQU 60 
LLastClick . EQU 64 
LNew .EQU 68 
LNextCell . EQU 72 
LRect . EQU 76 
Scroll . EQU 80 
LSearch . EQU 84 
LSetCell .EQU 88 
LSetSelect . EQU 92 
Size .EQU 96 
lUpdate . EQU 100 


List Record Data Structure 


rView List's display rectangle (rectangle; 8 bytes) 
port List's grafPort (portRec bytes) 

indent Indent distance (point; long) 

cellSize Cell size (point; long) 

visible Boundary of visible cells (rectangle; 8 bytes) 
vScroll Handle to vertical scroll bar 

hScroll Handle to horizontal scroll bar 

selFlags Selection flags (byte) 

lActive Nonzero if active (byte) 

clikTime Time of last click (long) 

clikLoc Position of last click (point; long) 

mouseLoc Current mouse location (point; long) 
LClLikLoop Pointer to routine to be called during LClick 
lastClick Last cell clicked (point; long) 

refCon Reference value (long) 

ListDefHandle Handle to list definition procedure 
userHandle Handle to user storage 

dataBounds Boundary of cells allocated (rectangle; 8 bytes) 
cells Handle to cell data 

maxIndex Used internally (word) 

cellArray Offsets to cells 


Trap Macro Name 


_ Pack 
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(Note: You can invoke each of the List Manager routines with a macro that has 
the same name as the routine preceded by an underscore. ) 
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Further Reference: 


Resource Manager 

QuickDraw 

Toolbox Event Manager 

Window Manager 

Package Manager 

Technical Note #203, Don't Abuse the Managers 


END OF DOCUMENT 
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